/*
 * Copyright 2005 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.jackrabbit.webdav;

/**
 * <code>DavLocatorFactory</code>...
 */
public interface DavLocatorFactory {

    /**
     * Create a new <code>DavResourceLocator</code>.
     *
     * @param prefix String consisting of  [scheme:][//authority][path] where
     * path defines the (imaginary) path to the {@link DavResourceLocator#isRootLocation root location}.
     * @param href of the resource to be created. The given string may start with
     * the 'prefix'. Please note, that in contrast to
     * {@link DavLocatorFactory#createResourceLocator(String, String, String)} the
     * href is expected to be URL encoded.
     * @return
     */
    public DavResourceLocator createResourceLocator(String prefix, String href);

    /**
     * Create a new <code>DavResourceLocator</code>. This methods corresponds to
     * {@link DavLocatorFactory#createResourceLocator(String, String, String, boolean)}
     * with the flag set to true.
     *
     * @param prefix String consisting of  [scheme:][//authority][path] where
     * path defines the path to the {@link DavResourceLocator#isRootLocation root location}.
     * @param workspacePath the first segment of the URIs path indicating the
     * workspace. The implementation may allow a empty String if workspaces
     * are not supported.
     * @param resourcePath the URL decoded resource path
     * @return
     */
    public DavResourceLocator createResourceLocator(String prefix, String workspacePath, String resourcePath);

    /**
     *
     * @param prefix
     * @param workspacePath
     * @param path
     * @param isResourcePath If true this method returns the same as
     * {@link DavLocatorFactory#createResourceLocator(String, String, String)},
     * otherwise the given path is treated as {@link javax.jcr.Item#getPath JCR path}.
     * The implementation may choose to modify the given item path if it contains
     * escaped characters due to incompatibility of the JCR path with the URI
     * definition. I.e. it would undo the modification that was applied when
     * calling {@link DavResourceLocator#getJcrPath()}.
     * @return
     * @see DavResourceLocator#getJcrPath()
     */
    public DavResourceLocator createResourceLocator(String prefix, String workspacePath, String path, boolean isResourcePath);
}